home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Sample Code / MoreFiles 1.3.1 / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-04-16  |  9.7 KB  |  275 lines  |  [TEXT/MMCC]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1995 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27. #define __MOREDESKTOPMGR__
  28.  
  29. #include <Types.h>
  30. #include <Files.h>
  31.  
  32. /*****************************************************************************/
  33.  
  34. pascal    OSErr    DTOpen(StringPtr volName,
  35.                        short vRefNum,
  36.                        short *dtRefNum,
  37.                        Boolean *newDTDatabase);
  38. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  39.     The DTOpen function opens a volume's desktop database. It returns
  40.     the reference number of the desktop database and indicates if the
  41.     desktop database was created as a result of this call (if it was created,
  42.     then it is empty).
  43.  
  44.     volName            input:    A pointer to the name of a mounted volume
  45.                             or nil.
  46.     vRefNum            input:    Volume specification.
  47.     dtRefNum        output:    The reference number of Desktop Manager's
  48.                             desktop database on the specified volume.
  49.     newDTDatabase    output:    true if the desktop database was created as a
  50.                             result of this call and thus empty.
  51.                             false if the desktop database was already created,
  52.                             or if it could not be determined if it was already
  53.                             created.
  54. */
  55.  
  56. /*****************************************************************************/
  57.  
  58. pascal    OSErr    DTGetAPPL(StringPtr volName,
  59.                           short vRefNum,
  60.                           OSType creator,
  61.                           short *applVRefNum,
  62.                           long *applParID,
  63.                           Str255 applName);
  64. /*    ¶ Find an application on a volume that can open a file with a given creator.
  65.     The DTGetAPPL function finds an application (file type 'APPL') with
  66.     the specified creator on the specified volume. It first tries to get
  67.     the application mapping from the desktop database. If that fails, then
  68.     it tries to find an application with the specified creator using
  69.     the File Manager's CatSearch routine. If that fails, then it tries to
  70.     find an application in the Desktop file.
  71.  
  72.     volName        input:    A pointer to the name of a mounted volume
  73.                         or nil.
  74.     vRefNum        input:    Volume specification.
  75.     creator        input:    The file's creator type.
  76.     applVRefNum    output:    The volume reference number of the volume the
  77.                         application is on.
  78.     applParID    output:    The parent directory ID of the application.
  79.     applName    output:    The name of the application.
  80.  
  81.     __________
  82.     
  83.     Also see:    FSpDTGetAPPL
  84. */
  85.  
  86. /*****************************************************************************/
  87.  
  88. pascal    OSErr    FSpDTGetAPPL(StringPtr volName,
  89.                              short vRefNum,
  90.                              OSType creator,
  91.                              FSSpec *spec);
  92. /*    ¶ Find an application on a volume that can open a file with a given creator.
  93.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  94.     the specified creator on the specified volume. It first tries to get
  95.     the application mapping from the desktop database. If that fails, then
  96.     it tries to find an application with the specified creator using
  97.     the File Manager's CatSearch routine. If that fails, then it tries to
  98.     find an application in the Desktop file.
  99.  
  100.     volName        input:    A pointer to the name of a mounted volume
  101.                         or nil.
  102.     vRefNum        input:    Volume specification.
  103.     creator        input:    The file's creator type.
  104.     spec        output:    FSSpec record containing the application name and
  105.                         location.
  106.  
  107.     __________
  108.     
  109.     Also see:    DTGetAPPL
  110. */
  111.  
  112. /*****************************************************************************/
  113.  
  114. pascal    OSErr    DTGetIcon(StringPtr volName,
  115.                           short vRefNum,
  116.                           short iconType,
  117.                           OSType fileCreator,
  118.                           OSType fileType,
  119.                           Handle *iconHandle);
  120. /*    ¶ Get an icon from the desktop database or Desktop file.
  121.     The DTGetIcon function retrieves the specified icon and returns it in
  122.     a newly created handle. The icon is retrieves from the Desktop Manager
  123.     or if the Desktop Manager is not available, from the Finder's Desktop
  124.     file. Your program is responsible for disposing of the handle when it is
  125.     done using the icon.
  126.  
  127.     volName        input:    A pointer to the name of a mounted volume
  128.                         or nil.
  129.     vRefNum        input:    Volume specification.
  130.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  131.                             kLargeIcon
  132.                             kLarge4BitIcon
  133.                             kLarge8BitIcon
  134.                             kSmallIcon
  135.                             kSmall4BitIcon
  136.                             kSmall8BitIcon
  137.     fileCreator    input:    The icon's creator type.
  138.     fileType    input:    The icon's file type.
  139.     iconHandle    output:    A Handle containing the newly created icon.
  140. */
  141.  
  142. /*****************************************************************************/
  143.  
  144. pascal    OSErr    DTSetComment(short vRefNum,
  145.                              long dirID,
  146.                              StringPtr name,
  147.                              ConstStr255Param comment);
  148. /*    ¶ Set a file or directory's Finder comment field.
  149.     The DTSetComment function sets a file or directory's Finder comment
  150.     field. The volume must support the Desktop Manager because you only
  151.     have read access to the Desktop file.
  152.  
  153.     vRefNum    input:    Volume specification.
  154.     dirID    input:    Directory ID.
  155.     name    input:    Pointer to object name, or nil when dirID
  156.                     specifies a directory that's the object.
  157.     comment    input:    The comment to add. Comments are limited to 200 characters;
  158.                     longer comments are truncated.
  159.  
  160.     __________
  161.     
  162.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  163.                 FSpDTGetComment
  164. */
  165.  
  166. /*****************************************************************************/
  167.  
  168. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  169.                                 ConstStr255Param comment);
  170. /*    ¶ Set a file or directory's Finder comment field.
  171.     The FSpDTSetComment function sets a file or directory's Finder comment
  172.     field. The volume must support the Desktop Manager because you only
  173.     have read access to the Desktop file.
  174.  
  175.     spec    input:    An FSSpec record specifying the file or directory.
  176.     comment    input:    The comment to add. Comments are limited to 200 characters;
  177.                     longer comments are truncated.
  178.  
  179.     __________
  180.     
  181.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  182.                 FSpDTGetComment
  183. */
  184.  
  185. /*****************************************************************************/
  186.  
  187. pascal    OSErr    DTGetComment(short vRefNum,
  188.                              long dirID,
  189.                              StringPtr name,
  190.                              Str255 comment);
  191. /*    ¶ Get a file or directory's Finder comment field (if any).
  192.     The DTGetComment function gets a file or directory's Finder comment
  193.     field (if any) from the Desktop Manager or if the Desktop Manager is
  194.     not available, from the Finder's Desktop file.
  195.  
  196.     vRefNum    input:    Volume specification.
  197.     dirID    input:    Directory ID.
  198.     name    input:    Pointer to object name, or nil when dirID
  199.                     specifies a directory that's the object.
  200.     comment    output:    A Str255 where the comment is to be returned.
  201.  
  202.     __________
  203.     
  204.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  205.                 FSpDTGetComment
  206. */
  207.  
  208. /*****************************************************************************/
  209.  
  210. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  211.                                 Str255 comment);
  212. /*    ¶ Get a file or directory's Finder comment field (if any).
  213.     The FSpDTGetComment function gets a file or directory's Finder comment
  214.     field (if any) from the Desktop Manager or if the Desktop Manager is
  215.     not available, from the Finder's Desktop file.
  216.  
  217.     spec    input:    An FSSpec record specifying the file or directory.
  218.     comment    output:    A Str255 where the comment is to be returned.
  219.  
  220.     __________
  221.     
  222.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  223.                 DTGetComment
  224. */
  225.  
  226. /*****************************************************************************/
  227.  
  228. pascal    OSErr    DTCopyComment(short srcVRefNum,
  229.                               long srcDirID,
  230.                               StringPtr srcName,
  231.                               short dstVRefNum,
  232.                               long dstDirID,
  233.                               StringPtr dstName);
  234. /*    ¶ Copy the file or folder comment from the source to the destination object.
  235.     The DTCopyComment function copies the file or folder comment from the
  236.     source to the destination object.  The destination volume must support
  237.     the Desktop Manager because you only have read access to the Desktop file.
  238.     
  239.     srcVRefNum    input:    Source volume specification.
  240.     srcDirID    input:    Source directory ID.
  241.     srcName        input:    Pointer to source object name, or nil when srcDirID
  242.                         specifies a directory that's the object.
  243.     dstVRefNum    input:    Destination volume specification.
  244.     dstDirID    input:    Destination directory ID.
  245.     dstName        input:    Pointer to destination object name, or nil when
  246.                         dstDirID specifies a directory that's the object.
  247.  
  248.     __________
  249.     
  250.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  251.                 FSpDTGetComment
  252. */
  253.  
  254. /*****************************************************************************/
  255.  
  256. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  257.                                  const FSSpec *dstSpec);
  258. /*    ¶ Copy the desktop database comment from the source to the destination object.
  259.     The FSpDTCopyComment function copies the desktop database comment from
  260.     the source to the destination object.  Both the source and the
  261.     destination volumes must support the Desktop Manager.
  262.     
  263.     srcSpec        input:    An FSSpec record specifying the source object.
  264.     dstSpec        input:    An FSSpec record specifying the destination object.
  265.  
  266.     __________
  267.     
  268.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  269.                 FSpDTGetComment
  270. */
  271.  
  272. /*****************************************************************************/
  273.  
  274. #endif    /* __MOREDESKTOPMGR__ */
  275.